home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / program / 441 / vdisrc12 / vdi@note.s next >
Text File  |  1990-11-23  |  6KB  |  118 lines
  1.  
  2. ;*========================================================================
  3. ;*
  4. ;* VDIFAST Public Domain VDI bindings.
  5. ;*
  6. ;*========================================================================
  7.  
  8. ;*************************************************************************
  9. ;* VDINOTES.
  10. ;*
  11. ;* There is nothing executable in this module.  The library's version
  12. ;* number is here, and can be queried at runtime by looking at global
  13. ;* variable '_vdif_version', which is defined below.  I don't know why
  14. ;* anyone would want to do that.
  15. ;*
  16. ;* Mostly this is a collection of notes about the library and its source.
  17. ;*
  18. ;* The following little blurb will never get linked into an application
  19. ;* unless the program specifically references the version variable's name.
  20. ;*
  21. ;*  Maintenance:
  22. ;*   02/06/89     - v1.1 Added 'vdiV0110' global label, so I can quickly
  23. ;*                  check the version # from an aln link-map.
  24. ;*************************************************************************
  25.  
  26. _vdif_version::
  27. vdiV0110::
  28.         dc.w    $0110          ;* version 01.10
  29.         dc.b    ' VDIFAST v1.10 '
  30.  
  31. ;*************************************************************************
  32. ;*
  33. ;*  Notes about the VDIFAST VDI bindings.
  34. ;*
  35. ;*  The object code & library are in 'DRI' format, & are thus compatible 
  36. ;*  with Alcyon C, Sozobon C, and any other compiler/linker which can handle
  37. ;*  'DRI-compatible' object files (v0.92:  Laser C compatible).
  38. ;*  
  39. ;*  When used with the Atari 'aln' linker, you must first use the 'DOINDEX'
  40. ;*  program to create a .NDX index file for the library.
  41. ;*
  42. ;*  These bindings were written to be both fast, and frugal of memory.
  43. ;*  In most cases, when a pointer to an array (such as x/y coordinates for
  44. ;*  polylines) is passed to the bindings, that pointer is placed directly
  45. ;*  into the VDI 'contrl' structure.  When an intermediate array is needed
  46. ;*  (such as for the text functions), stack space will be used for temporary
  47. ;*  storage.  Since no global data space or bss space is allocated by these
  48. ;*  bindings, the amount of runtime memory used is about 1/2 of the size of
  49. ;*  the object modules which are linked into your program.  (DRI object 
  50. ;*  modules before linking are roughly twice the size they will be after
  51. ;*  linking.)  Thus, if you write a program that causes every module in the
  52. ;*  library to be included, the overhead added to your program will be less
  53. ;*  than 5k.
  54. ;*  
  55. ;*  You do NOT need to define the typical VDI arrays 'contrl', 'intin', 
  56. ;*  'intout', 'ptsin', and 'ptsout' in your C program!  (At least, not for 
  57. ;*  the use of these bindings...you may certainly use variables/arrays of
  58. ;*  those names if you find it convenient to do so for some reason.)
  59. ;*  
  60. ;*  The stack space used by these bindings in processing a typical VDI call
  61. ;*  is 30-50 bytes.  For the text-oriented calls, it will be approximately
  62. ;*  40 bytes plus twice the length of the string to be input/output.  In
  63. ;*  other words, a normal stack size should work just fine (I generally use
  64. ;*  a 1k stack without problems).
  65. ;*  
  66. ;*  The library contains no global symbols other than the function names
  67. ;*  themselves.  There are no external references within any of the modules;*  
  68. ;*  each is self-contained.  It should never be necessary to make multiple 
  69. ;*  passes of the linker to resolve all references, and it shouldn't matter
  70. ;*  where the VDIFAST name appears on the linker's command line.
  71. ;*
  72. ;*  This code was developed using the Digital Research publication _VDI
  73. ;*  Programmer's Guide_.  There may be differences between the DRI docs
  74. ;*  and the Abacus _GEM Programmer's Guide_, especially in the inquiry
  75. ;*  functions.  Sorry, but it seemed safest to use the DRI docs as the
  76. ;*  definitive source.
  77. ;*  
  78. ;*  There are some (obscure) functions which are not supported, notably
  79. ;*  the cell_array functions, and the VDI Escapes related to the Polaroid
  80. ;*  Palette Processor (whatever that is) and metafiles.
  81. ;*
  82. ;*  This code was developed under Atari's MadMac assembler, and probably
  83. ;*  won't assemble correctly on any other assembler. To convert this code 
  84. ;*  to another assembler, the following notes may be of use:
  85. ;*  
  86. ;*    All comments are preceded by ';*', most assemblers use the '*' for a
  87. ;*    comment delimiter.  Using an editor, do a 'search and replace all'
  88. ;*    to change ';*' to '*;'.  Please don't change them to just an '*',
  89. ;*    because trying to change them back will also catch computed constants
  90. ;*    such as 'move.l   4*SIZE,d0'.
  91. ;*    
  92. ;*    The MadMac '.cargs' opcode is used extensively.  This opcode simply
  93. ;*    generates equates for the named symbols; for another assembler, you
  94. ;*    can comment out the .cargs line and add normal equates, as follows:
  95. ;*    
  96. ;*       ;* .cargs  #8,.handle.w,.pxy.l,.color.w
  97. ;*       .handle = 8
  98. ;*       .pxy    = 10
  99. ;*       .color  = 14  
  100. ;*
  101. ;*    MadMac recognizes symbols starting with a '.' as local symbols, 
  102. ;*    limited in scope to the nearest surrounding non-local symbols.  For
  103. ;*    an assembler that doesn't use local symbols, you're gonna be spending
  104. ;*    a LOT of time removing leading '.' characters and thinking up unique
  105. ;*    names for everything.
  106. ;*    
  107. ;*    A single macro is used extensively.  This macro, called 'VContrl' is
  108. ;*    used as a coding shortcut to set up the VDI 'contrl' structure for
  109. ;*    each call.  If your assembler doesn't support macros, you are going
  110. ;*    to have to (tediously) change each occurance of 'VContrl' to the
  111. ;*    equivelent assembler code.
  112. ;*    
  113. ;*
  114. ;*************************************************************************
  115.  
  116. ;       end of code
  117.  
  118.